---
sidebar_label: Databases
sidebar_position: 1
description: Manage databases with the Hasura Metadata API
keywords:
  - hasura
  - docs
  - Metadata API
  - API reference
  - database
  - source
---

# Metadata API Reference: Databases

## Introduction

Add/remove databases in Hasura GraphQL Engine.

:::tip Supported from

The Metadata API is supported for versions `v2.0.0` and above and
replaces the older [schema/Metadata API](/api-reference/schema-metadata-api/index.mdx).

:::

## pg_add_source {#metadata-pg-add-source}

`pg_add_source` is used to connect a Postgres database to Hasura.

Add a database with name `pg1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_add_source",
  "args": {
    "name": "pg1",
    "configuration": {
      "connection_info": {
        "database_url": {
           "from_env": "<DB_URL_ENV_VAR>"
         },
        "pool_settings": {
          "max_connections": 50,
          "idle_timeout": 180,
          "retries": 1,
          "pool_timeout": 360,
          "connection_lifetime": 600
        },
        "use_prepared_statements": true,
        "isolation_level": "read-committed"
      },
      "connection_template": {
        "template": "{{ if $.request.session?[\"x-hasura-role\"] == \"admin\" }} {{$.primary}} {{else}} {{$.connection_set.db_1}} {{ end }}"
      },
      "connection_set": [
        {
          "name": "db_1",
          "connection_info": {
            "database_url": {
              "from_env": "<DB_URL_ENV_VAR>"
            }
          }
        }
      ]
    },
    "replace_configuration": false,
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      },
      "naming_convention": "hasura-default"
    }
  }
}
```

### Args syntax {#metadata-pg-add-source-syntax}

| Key                   | Required | Schema                                                                    | Description                                                                                                                           |
| --------------------- | -------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name                  | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                   | Name of the Postgres database                                                                                                         |
| configuration         | true     | [PGConfiguration](/api-reference/syntax-defs.mdx#pgconfiguration)         | Database connection configuration                                                                                                     |
| replace_configuration | false    | Boolean                                                                   | If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`) |
| customization         | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization) | Customize root fields and type names for the source                                                                                   |

:::tip Deprecated field

The `replace_configuration` field is deprecated in favour of the
[pg_update_source API](/api-reference/metadata-api/source.mdx#metadata-pg-update-source).

:::

:::tip Note

The schema specified in the `extensions_schema` is expected to exist in the [search path](https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH)
of your database.

:::

## pg_drop_source {#metadata-pg-drop-source}

`pg_drop_source` is used to remove a Postgres database from Hasura.

Remove a database with name `pg1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_drop_source",
  "args": {
    "name": "pg1",
    "cascade": true
  }
}
```

### Args syntax {#metadata-pg-drop-source-syntax}

| Key     | Required | Schema                                                  | Description                                                                                                                                                        |
| ------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name    | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the Postgres database                                                                                                                                      |
| cascade | false    | Boolean                                                 | When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: `false`) |

## pg_get_source_tables {#metadata-pg-get-source-tables}

`pg_get_source_tables` is used to list the tables available on a given Postgres
database.

List the tables available on a database with name `pg1`:

```http
{
  "type": "pg_get_source_tables",
  "args": {
    "source": "pg1"
  }
}
```

### Args syntax {#metadata-pg-get-source-tables-syntax}

| Key    | Required | Schema                                                  | Description                   |
| ------ | -------- | ------------------------------------------------------- | ------------------------------|
| source | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the Postgres database |

## rename_source {#metadata-rename-source}

`rename_source` is used to rename an existing source.

Given there already exists a database with name `pg1`, we can rename it to `pg2` using:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "rename_source",
  "args": {
    "name": "pg1",
    "new_name": "pg2"
  }
}
```

Note that all settings are kept, only the name is changed.

### Args syntax {#metadata-rename-source-syntax}

| Key      | Required | Schema                                                  | Description          |
| -------- | -------- | ------------------------------------------------------- | -------------------- |
| name     | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the database |
| new_name | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the database |

## pg_update_source {#metadata-pg-update-source}

`pg_update_source` is used to update Postgres source in Hasura.

Update a database with name `pg1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_update_source",
  "args": {
    "name": "pg1",
    "configuration": {
      "connection_info": {
        "database_url": {
           "from_env": "<DB_URL_ENV_VAR>"
         },
        "pool_settings": {
          "max_connections": 50,
          "idle_timeout": 180,
          "retries": 1,
          "pool_timeout": 360,
          "connection_lifetime": 600
        },
        "use_prepared_statements": true,
        "isolation_level": "read-committed",
      }
    },
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      },
      "naming_convention": "hasura-default"
    }
  }
}
```

### Args syntax {#metadata-pg-update-source-syntax}

| Key           | Required | Schema                                                                    | Description                                         |
| ------------- | -------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
| name          | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                   | Name of the Postgres database                       |
| configuration | false    | [PGConfiguration](/api-reference/syntax-defs.mdx#pgconfiguration)         | Database connection configuration                   |
| customization | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization) | Customize root fields and type names for the source |

## mssql_add_source {#mssql-add-source}

`mssql_add_source` is used to connect an MS SQL Server database to Hasura.

Add a database with name `mssql1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "mssql_add_source",
  "args": {
    "name": "mssql1",
    "configuration": {
      "connection_info": {
        "connection_string": {
           "from_env": "<CONN_STRING_ENV_VAR>"
         },
        "pool_settings": {
          "max_connections": 50,
          "idle_timeout": 180
        }
      }
    },
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      }
    }
  }
}
```

### Args syntax {#mssql-add-source-syntax}

| Key                   | Required | Schema                                                                    | Description                                                                                                                           |
| --------------------- | -------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name                  | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                   | Name of the MS SQL Server database                                                                                                    |
| configuration         | true     | [MsSQLConfiguration](/api-reference/syntax-defs.mdx#mssqlconfiguration)   | Database connection configuration                                                                                                     |
| replace_configuration | false    | Boolean                                                                   | If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`) |
| customization         | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization) | Customize root fields and type names for the source                                                                                   |

:::tip Deprecated field

The `replace_configuration` field is deprecated in favour of the
[mssql_update_source API](/api-reference/metadata-api/source.mdx#mssql-update-source).

:::

## mssql_drop_source {#mssql-drop-source}

`mssql_drop_source` is used to remove an MS SQL Server database from Hasura.

Remove a database with name `mssql1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "mssql_drop_source",
  "args": {
    "name": "mssql1"
  }
}
```

### Args syntax {#mssql-drop-source-syntax}

| Key     | Required | Schema                                                  | Description                                                                                                                                                        |
| ------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name    | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the MS SQL Server database                                                                                                                                 |
| cascade | false    | Boolean                                                 | When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: `false`) |

## mssql_get_source_tables {#mssql-get-source-tables}

`mssql_get_source_tables` is used to list the tables available on a given
MS SQL Server database.

List the tables available on a database with name `mssql1`:

```http
{
  "type": "mssql_get_source_tables",
  "args": {
    "source": "mssql1"
  }
}
```

### Args syntax {#mssql-get-source-tables-syntax}

| Key    | Required | Schema                                                  | Description                        |
| ------ | -------- | ------------------------------------------------------- | ---------------------------------- |
| source | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the MS SQL Server database |

## mssql_update_source {#mssql-update-source}

`mssql_update_source` is used to update an already existing MS SQL Server source in Hasura.

Update a database with name `mssql1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "mssql_update_source",
  "args": {
    "name": "mssql1",
    "configuration": {
      "connection_info": {
        "connection_string": {
           "from_env": "<CONN_STRING_ENV_VAR>"
         },
        "pool_settings": {
          "max_connections": 50,
          "idle_timeout": 180
        }
      }
    },
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      }
    }
  }
}
```

### Args syntax {#mssql-update-source-syntax}

| Key           | Required | Schema                                                                    | Description                                         |
| ------------- | -------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
| name          | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                   | Name of the MS SQL Server database                  |
| configuration | false    | [MsSQLConfiguration](/api-reference/syntax-defs.mdx#mssqlconfiguration)   | Database connection configuration                   |
| customization | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization) | Customize root fields and type names for the source |

## bigquery_add_source {#metadata-bigquery-add-source}

`bigquery_add_source` is used to connect a BigQuery database to Hasura.

Add a database with name `bigquery1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "bigquery_add_source",
  "args": {
    "name": "bigquery1",
    "configuration": {
      "service_account": "bigquery_service_account",
      "project_id": "bigquery_project_id",
      "datasets": ["dataset1", "dataset2"]
    },
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      }
    }
  }
}
```

### Args syntax {#metadata-bigquery-add-source-syntax}

| Key                   | Required | Schema                                                                        | Description                                                                                                                           |
| --------------------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name                  | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                       | Name of the BigQuery database                                                                                                         |
| configuration         | true     | [BigQueryConfiguration](/api-reference/syntax-defs.mdx#bigqueryconfiguration) | Database connection configuration                                                                                                     |
| replace_configuration | false    | Boolean                                                                       | If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`) |
| customization         | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization)     | Customize root fields and type names for the source                                                                                   |

:::tip Deprecated field

The `replace_configuration` field is deprecated in favour of the
[bigquery_update_source API](/api-reference/metadata-api/source.mdx#metadata-bigquery-update-source).

:::

## bigquery_drop_source {#metadata-bigquery-drop-source}

`bigquery_drop_source` is used to remove a BigQuery database from Hasura.

Remove a database with name `bigquery1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "bigquery_drop_source",
  "args": {
    "name": "bigquery1"
  }
}
```

### Args syntax {#metadata-bigquery-drop-source-syntax}

| Key     | Required | Schema                                                  | Description                                                                                                                                                        |
| ------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name    | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename) | Name of the BigQuery database                                                                                                                                      |
| cascade | false    | Boolean                                                 | When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: `false`) |

## bigquery_update_source {#metadata-bigquery-update-source}

`bigquery_update_source` is used to update an already existing BigQuery source in Hasura.

Update a database with name `bigquery1`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "bigquery_update_source",
  "args": {
    "name": "bigquery1",
    "configuration": {
      "service_account": "bigquery_service_account",
      "project_id": "bigquery_project_id",
      "datasets": ["dataset1", "dataset2"]
    },
    "customization": {
      "root_fields": {
        "namespace": "some_field_name",
        "prefix": "some_field_name_prefix",
        "suffix": "some_field_name_suffix"
      },
      "type_names": {
        "prefix": "some_type_name_prefix",
        "suffix": "some_type_name_suffix"
      }
    }
  }
}
```

### Args syntax {#metadata-bigquery-update-source-syntax}

| Key           | Required | Schema                                                                        | Description                                         |
| ------------- | -------- | ----------------------------------------------------------------------------- | --------------------------------------------------- |
| name          | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                       | Name of the BigQuery database                       |
| configuration | false    | [BigQueryConfiguration](/api-reference/syntax-defs.mdx#bigqueryconfiguration) | Database connection configuration                   |
| customization | false    | [SourceCustomization](/api-reference/syntax-defs.mdx#sourcecustomization)     | Customize root fields and type names for the source |
